home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Scene Storm
/
Scene Storm - Volume 1.iso
/
coding
/
c
/
toollib
/
tool.doc
< prev
next >
Wrap
Text File
|
1995-12-30
|
42KB
|
1,184 lines
tool.library version 8.1
© Copyright 1990-91 Jaba Development
written with the Devpac Assembler version 2.14 by
Jan van den Baard
DISCLAIMER
----------------------------------------------------------------------------
The author takes no responsibility as to the suitability or accuracy of this
documentation and/or the program(s) it describes. Any damage sustained by the
use of this documentation and/or the program(s) it describes is the sole
responsibility of the user her/him self.
----------------------------------------------------------------------------
COPYRIGHT
----------------------------------------------------------------------------
tool.library, © Copyright 1990-91 by Jaba Development. All rights reserved.
This program may be distributed non-commercially only providing that the
source code, documentation and copyright notice remains intact. This program
is FREEWARE so no financial donation is necessary (but welcome).
----------------------------------------------------------------------------
This is version 8.1 of a shared library containing 46 useful functions for
all kinds of programs. The functions in this library are not of a specific
kind but cover a lot of the Amiga facilities. There are functions for ports
, sorting, gadgets, memory, string, directory and file handling. This manual
is divided into the following sections:
THE ROUTINES I.
STRUCTURES AND DEFINITIONS II.
THE FILEREQUESTER III.
HISTORY IV.
NOTES V.
----------------------------------------------------------------------------
I. THE ROUTINES
----------------------------------------------------------------------------
NAME
Port = CreatePort( Name, Pri );
D0 -30 A0 D0
FUNCTION
To allocate and set up a message port.
INPUTS
Name - A pointer to a NULL terminated string representing the
name of the message port or NULL if the port should not
be globaly recognizable to other tasks.
Pri - A 32 bit integer representing the message port priority.
RESULT
"Port" will be a pointer to the newly created message port or
NULL if an error occurred.
NOTE: The message port is only added to the system port-list if
you specify a name for it. If you don't the port can not
be found by other tasks.
NAME
DeletePort( Port );
-36 A0
FUNCTION
To deallocate and remove a message port.
INPUTS
Port - A pointer to the message port that is to be deleted.
RESULT
The message port is removed and deallocated.
NAME
IOReq = CreateExtIO( Port, Size );
D0 -42 A0 D0
FUNCTION
To allocates and initialize an IORequest structure.
INPUTS
Port - A pointer to the message port which is signalled if a message
is executed.
Size - A 32 bit integer that represents the size if the IORequest
structure.
RESULT
"IOReq" will be a pointer to the allocated and initialized IORequest
structure or NULL if an error occurred.
NAME
DeleteExtIO( IOReq );
-48 A0
FUNCTION
To deallocate an IORequest structure.
INPUTS
IOReq - A pointer to the IORequest structure to be deallocated.
NAME
IOReq = CreateStdIO( Port );
D0 -54 A0
FUNCTION
To allocate and initialize an IOStdReq structure.
INPUTS
Port - A pointer to the message port which is signalled if a message
is executed.
RESULT
"IOReq" will be a pointer to the allocated and initialized IOStdReq
structure or NULL if an error occurred.
NAME
DeleteStdIO( IOReq );
-60 A0
FUNCTION
To deallocate an IOStdReq structure.
INPUTS
IOReq - A pointer to the IOStdReq structure to be deallocated.
NAME
timedelay = CreateTimeDelay(port,seconds,micros);
D0 -66 A0 D0 D1
FUNCTION
Sets up the timer.device to be able to put a task to sleep for a
precise amount of time.
INPUTS
port - A pointer to a message port which, if this port was
signalled, wakes up the task before the time ran out.
This may also be NULL but that makes it impossible to
stop the delay before the time runs out.
seconds - A 32-bit integer representing the amount of seconds to
put the task to sleep.
micros - A 32-bit integer representing the amount of microseconds
to put the task to sleep.
RESULT
timedelay - A pointer to a TimeDelay structure or NULL if an error
occurred.
NAME
yourmsg = DoTimeDelay(timedelay);
-72 A0
FUNCTION
To put a task to sleep for a specific time.
INPUTS
timdelay - A pointer to a TimeDelay structure as returned by
"CreateTimeDelay".
RESULT
"yourmsg" will be TRUE if the routine breaks off because it has
been signalled by the message port supplied by you and FALSE if
the time ran out.
NAME
DeleteTimeDelay(timedelay);
-78 A0
FUNCTION
To deallocate and erase the TimeDelay structure and close all of it's
resources.
INPUTS
timdelay - A pointer to a TimeDelay structure as returned by
"CreateTimeDelay".
NAME
QuickSort( Base, Num, Size, Compar );
-84 A0 D0 D1 A1
FUNCTION
To sort an array of elements.
INPUTS
Base - A pointer to the first element in the array.
Num - A 32 bit integer representing the number of elements in the
array.
Size - A 32 bit integer representing the size of an element.
NOTE: The size of an element may NOT be larger than 64
KBytes.
Compar - A pointer to a routine that does the comparison between
two elements. This is called like this:
Compar(a,b);
The arguments "a" and "b" are pushed on the stack before
calling the routine. Also a pointer to argument "a" is put
in A0 and a pointer to argument "b" is put in A1 for the
assembler programmers. The routine must return a 32 bit
integer. It should return -1, 0 or 1 depending on whether
element "a" is to be considered smaller, equal or bigger than
element "b". The comparison routine is passed POINTERS to
the elements in the array.
NAME
SwapMem( MemA, MemB, Size );
-90 A0 A1 D0
FUNCTION
To exchange two areas of memory.
INPUTS
MemA - A pointer to the first block of memory.
MemB - A pointer to the second block of memory.
Size - A 32 bit integer representing the size in bytes of the two
memory areas.
NOTE: The memory areas swapped can NOT be larger than 64 KByte.
NAME
Set = TestBits( Value, Bits );
D0 -96 D0 D1
FUNCTION
To test whether or not certain bits are set in a value.
INPUTS
Value - A 32 bit integer representing the value in which the bits
are tested.
Bits - A 32 bit integer representing the bits to be tested.
RESULT
Set will be TRUE if the bits where set in "Value" and FALSE if not.
NAME
SelectGadget( Window, Gadget, Req );
-102 A0 A1 A2
FUNCTION
To visually select a gadget. Also the SELECTED flag in the "Flags"
field of the gadget will be set.
INPUTS
Window - A pointer to the window in which the gadget is located.
Gadget - A pointer to the gadget which must be selected.
NOTE: Only gadget of the "TOGGLESELECT" type will be
selected.
Req - If the gadget is located in a requester you must put a
pointer to that requester here. If no requester is used
put NULL here.
NAME
DeSelectGadget( Window, Gadget, Req );
-108 A0 A1 A2
FUNCTION
To visually select a gadget. Also the SELECTED flag in the "Flags"
field of the gadget will be cleared.
INPUTS
Window - A pointer to the window in which the gadget is located.
Gadget - A pointer to the gadget which must be de-selected.
NOTE: Only gadget of the "TOGGLESELECT" type will be
de-selected.
Req - If the gadget is located in a requester you must put a
pointer to that requester here. If no requester is used
put NULL here.
NAME
MutualExclude( Window, Gadget, From, Req );
-114 A0 A1 A2 A3
FUNCTION
To mutually exclude gadgets if a certain gadget is selected.
INPUTS
Window - A pointer to the window in which the gadgets are located.
Gadget - A pointer to the gadget which does the MutualExcluding.
The "MutualExclude" field of this gadget represents the
gadgets to be mutually excluded. Every set bit represents
a gadget that should be de-selected if this gadget is
selected.
From - A pointer to the first gadget in a list from which the
routine starts to look for gadgets to be de-selected.
NOTE: Only gadgets of the "TOGGLESELECT" type will be
mutually excluded.
Req - If the gadgets are located in a requester you must put a
pointer to that requester here. If no requester is used
put NULL here.
NAME
MutualInclude( Window, Gadget, From, Req );
-120 A0 A1 A2 A3
FUNCTION
To mutually include gadgets if a certain gadget is selected.
INPUTS
Window - A pointer to the window in which the gadgets are located.
Gadget - A pointer to the gadget which does the MutualIncluding.
The "MutualExclude" field of this gadget represents the
gadgets to be mutually included. Every set bit represents
a gadget that should be selected if this gadget is
selected.
From - A pointer to the first gadget in a list from which the
routine starts to look for gadgets to be selected.
NOTE: Only gadgets of the "TOGGLESELECT" type will be
mutually included.
Req - If the gadgets are located in a requester you must put a
pointer to that requester here. If no requester is used
put NULL here.
NAME
EraseGadget( Window, Gadget, Req );
-126 A0 A1 A2
FUNCTION
To erase a gadget from the window or requester.
INPUTS
Window - A pointer to the window in which the gadget is located.
Gadget - A pointer to the gadget which must be erased.
Req - If the gadget is located in a requester you must put a
pointer to that requester here. If no requester is used
put NULL here.
NAME
GadgetOn( Window, Gadget, Req );
-132 A0 A1 A2
FUNCTION
To enable a gadget to be being clicked.
It's basically the same as Intuition's "OnGadget" only this
routine first erases the gadget from the display and then refreshes
only the gadget switched on.
INPUTS
Window - A pointer to the window in which the gadget is located.
Gadget - A pointer to the gadget which must be switched on.
Req - If the gadget is located in a requester you must put a
pointer to that requester here. If no requester is used
put NULL here.
NAME
GadgetOff( Window, Gadget, Req );
-138 A0 A1 A2
FUNCTION
To disable a gadget from being clicked.
It's basically the same as Intuition's "OffGadget" only this
routine first erases the gadget from the display and then refreshes
only the gadget switched off.
INPUTS
Window - A pointer to the window in which the gadget is located.
Gadget - A pointer to the gadget which must be switched off.
Req - If the gadget is located in a requester you must put a
pointer to that requester here. If no requester is used
put NULL here.
NAME
sel = SelectTest( Gadget );
D0 -144 A0
FUNCTION
To test if a gadget is selected or not.
INPUTS
Gadget - A pointer to the gadget which is tested.
RESULTS
"sel" will be TRUE if the gadget is selected and FALSE if not.
NAME
ShadowGadget( Window, Gadget, Req, Color );
-150 A0 A1 A2 D0
FUNCTION
To draw a shadow around the gadget in the specified color.
INPUTS
Window - A pointer to the window in which the gadget is located.
Gadget - A pointer to the gadget at which a shadow is drawed.
Req - If the gadget is located in a requester you must put a
pointer to that requester here. If no requester is used
put NULL here.
Color - A 32 bit integer representing the pen number in which the
shadow is drawed.
NAME
OnGList( Window, First, Req, Numgad );
-156 A0 A1 A2 D0
FUNCTION
To switch a complete list of gadgets on.
INPUTS
Window - See GadgetOn
First - A pointer to the first gadget in the list to be switched on.
Req - See GadgetOn
NumGad - A 32 bit integer representing the number of gadgets to be
switch on. If you put -1 here all the gadgets in the list
are switched on.
NAME
OffGList( Window, First, Req, Numgad );
-162 A0 A1 A2 D0
FUNCTION
To switch a complete list of gadgets off.
INPUTS
Window - See GadgetOff
First - A pointer to the first gadget in the list to be switched off.
Req - See GadgetOff
NumGad - A 32 bit integer representing the number of gadgets to be
switch off. If you put -1 here all the gadgets in the list
are switched off.
NAME
SelectGList( Window, First, Req, Numgad );
-168 A0 A1 A2 D0
FUNCTION
To select a complete list of gadgets.
INPUTS
Window - See SelectGadget
First - A pointer to the first gadget in the list to be selected.
NOTE: Only gadget of the "TOGGLESELECT" type can be
selected.
Req - See SelectGadget
NumGad - A 32 bit integer representing the number of gadgets to be
selected. If you put -1 here all the gadgets in the list
are selected.
NAME
DeSelectGList( Window, First, Req, Numgad );
-174 A0 A1 A2 D0
FUNCTION
To de-select a complete list of gadgets.
INPUTS
Window - See DeSelectGadget
First - A pointer to the first gadget in the list to be de-selected.
NOTE: Only gadget of the "TOGGLESELECT" type can be
de-selected.
Req - See DeSelectGadget
NumGad - A 32 bit integer representing the number of gadgets to be
de-selected. If you put -1 here all the gadgets in the list
are de-selected.
NAME
ShadowGList( Window, First, Req, Color, Numgad );
-180 A0 A1 A2 D0 D1
FUNCTION
To draw shadows around a complete list of gadgets.
INPUTS
Window - See ShadowGadget
First - A pointer to the first gadget in the list to be shadowed.
Req - See ShadowGadget
Color - See ShadowGadget
NumGad - A 32 bit integer representing the number of gadgets to be
shadowed. If you put -1 here all the gadgets in the list
are shadowed.
NAME
EraseGList( Window, First, Req, Numgad );
-186 A0 A1 A2 D0
FUNCTION
To erase a complete list of gadgets from a window or a requester.
INPUTS
Window - See EraseGadget
First - A pointer to the first gadget in the list to be erased.
Req - See EraseGadget
NumGad - A 32 bit integer representing the number of gadgets to be
erased. If you put -1 here all the gadgets in the list
are erased.
NAME
InitMemoryChain(chain,size)
-192 A0 D0
FUNCTION
To initialize a MemoryChain structure for use.
INPUTS
chain - A pointer to a MemoryChain structure.
size - A 32-bit integer representing the size of a MemoryBlock.
NAME
memptr = AllocItem(chain,size,reqs);
D0 -198 A0 D0 D1
FUNCTION
To allocate a chunk of memory in a MemoryChain.
INPUTS
chain - A pointer to the MemoryChain in which the memory will be
allocated.
size - A 32-bit integer representing the size of the memory.
reqs - A 32-bit integer representing the memory requirements
of the allocation.
NOTE: The size is always rounded up to the nearest multiple of 8.
RESULT
memptr - A pointer to the allocated memory or NULL if the allocation
failed.
NOTE: The memory is always allocated in a longword boundary.
NAME
FreeItem(chain,memptr,size)
-204 A0 A1 D0
FUNCTION
To deallocate a chunk of memory allocated with AllocItem from a
MemoryChain.
INPUTS
chain - A pointer to the MemoryChain in which the memory was
allocated.
memptr - A pointer to the memory.
size - A 32 bit integer representing the size to be freed.
NAME
FreeMemoryChain(chain)
-210 A0
FUNCTION
To deallocate and re-initialize a complete MemoryChain.
INPUTS
chain - A pointer to the MemoryChain
RESULT
All memory allocated for the MemoryChain is deallocated and the
MemoryChain structure itself is re-initialized so that it can
be used again.
NAME
Format( Buffer, FString, Args );
-216 A0 A1 A2
FUNCTION
To format an output into a specified buffer.
INPUTS
Buffer - A pointer to a buffer in which the formatted output is
copied. NOTE: You must make sure that the buffer is big
enough to hold the formatted output.
FString - A pointer to a NULL terminated string explaining how to
interpret the arguments. The following format specifiers
are supported:
%lc - the next long word in the argument array is
formatted as a 8 bit character.
%ld - the next long word in the argument array is
formatted as a 32 bit decimal number.
%lx - the next long word in the argument array is
formatted as a 32 bit hexadecimal number.
%ls - the next long word in the argument array is
formatted as a pointer to a NULL terminated
string.
The "l" in these format specifiers is only necessary
when the arguments are 32 bit. Following this "l" sign
you may also specify the following:
-> An optional minus sign to tell the routine to left
justify the next formatted item within the field
width
-> An optional digit string to tell the routine to fill
out the formatted item with spaces. If the digit string
is preceeded with a "0" character the item will be
filled out with "0" characters instead of spaces.
-> An optional period sign to separate the field width
specifier from the maximum characters specifier.
-> An optional digit string (for %ls and %s only) to tell
the routine the maximum amount of characters to format
from the string.
This routine is based on Exec's function "RawDoFmt()" which
does NOT support any form of floating point formatting.
If you have to format floating point numbers you will have
to use "sprintf" from the standard C library.
Args - A pointer to an array in which the arguments are stored.
NOTE: C programmers must link with "tool.lib" to get the
arguments passed correctly to the routine.
NAME
num = WriteFormat( Handle, FString, Args );
D0 -222 A0 A1 A2
FUNCTION
To format an output and writes the result directly to a file.
INPUTS
Handle - A pointer to an AmigaDOS filehandle to which the formatted
result will be written.
FString - A pointer to a NULL terminated format string which can
hold the same format specifiers as the format string from
"Format". NOTE: The formatted output may NOT be larger
that 512 bytes (including the terminating 0 byte.).
Args - A pointer to an array in which the arguments are stored.
NOTE: C programmers must link with "tool.lib" to get the
arguments passed correctly to the routine.
RESULT
"num" will read the exact amount of characters written to the file or
-1 if an error occurred.
NAME
match = MatchPattern( String, Pattern, Case );
D0 -228 A0 A1 D0
FUNCTION
To perform a Unix style pattern match on a string.
INPUTS
String - A pointer to a NULL terminated string which will be matched
with the pattern.
Pattern - A pointer to a NULL terminated string which represents
the pattern to be matched. The pattern may have the
following wildcards:
"*" - representing any number of characters.
"?" - representing a single character.
Case - A 32 bit boolean value which must be "CASE" if the routine
should also check the character case and "NO_CASE" if not.
RESULT
"match" will read TRUE if the string matched the pattern and FALSE
if not.
NAME
pat = Isolate( Path, Buffer );
D0 -234 A0 A1
FUNCTION
To scan a full pathname for a wildcard expansion and copy it, if
found, into a buffer.
INPUTS
Path - A pointer to a NULL terminated full AmigaDOS pathname.
If a pattern was found at the end of the pathname this
pattern will be copied into the buffer and the pathname
will be truncated at the point where the pattern was found.
NOTE: This routine only isolates patterns which has atleast
one wildcard in it.
Buffer - A pointer to a buffer in which the pattern, if found, is
copied.
RESULT
"pat" will be TRUE if a pattern was found and FALSE if not.
NAME
BstrToCstr( Bstr, Buffer );
-240 A0 A1
FUNCTION
To convert a BSTR string into a standard NULL terminated string.
INPUTS
Bstr - A BPTR to a BSTR string.
Buffer - A buffer in which the string is copied.
NAME
return = GetDate( DateStamp, Buffer, How);
D0 -246 A0 A1 D0
FUNCTION
To convert a "DateStamp" structure into an ASCII string.
INPUTS
DateStamp - A pointer to an initialized DateStamp structure
or NULL for the current System time.
Buffer - A pointer to a buffer which can hold atleast "MINDATE"
bytes.
How - A 32 bit integer explaining what to convert.
For example lets say that it is thursday 20 september
1990 and it's 13:30:00 hour.
The result after a call to GetDate will be:
ALL - Thursday 20-09-1990 13:30:00
ONLY_DAY - Thursday
ONLY_DATE - 20-09-1990
ONLY_TIME - 13:30:00
RESULTS
return will be TRUE if the conversion succeeded or FALSE if it failed
"Buffer" contains the converted ASCII form of "DateStamp" or the
System time.
NAME
succes = OpenDir(directory,name);
D0 -252 A0 A1
FUNCTION
To open a directory.
INPUTS
directory - A pointer to a Directory structure.
name - A pointer to a NULL terminated string representing the
name of the directory.
RESULT
success - this reads TRUE if the directory opens successfully and
FALSE if an error occurred.
NAME
entry = GetEntry(directory);
D0 -258 A0
FUNCTION
To read the next entry of the directory into memory.
INPUTS
directory - A pointer to the Directory structure.
RESULT
entry - this will be a pointer to an EntryInfo structure or NULL.
If NULL is returned this could mean that an error occurred.
A call to IoErr should read ERROR_NO_MORE_ENTRIES otherwise
an error has occurred.
NOTE: The directory is automatically UnLocked when the last
entry was read.
NAME
CloseDir(directory)
-264 A0
FUNCTION
To UnLock the directory.
INPUTS
directory - A pointer to the directory structure.
NAME
FreeDir(directory);
-270 A0
FUNCTION
To deallocate the memory a directory takes up.
INPUTS
directory - A pointer to the directory structure.
NAME
string = IoErrToStr()
D0 -276
FUNCTION
To convert a DOS error into an ASCII form.
RESULTS
string - this will be a pointer to a string representing the ASCII
form of a DOS error or NULL if IoErr returned an unknown
code.
NAME
Freq = AllocFreq();
D0 -282
FUNCTION
To allocate and initialize a FileRequester structure.
RESULT
Freq - this will be a pointer to an allocated and initialized
FileRequester structure or NULL if the Allocation failed.
NAME
FreeFreq( Freq );
-288 A0
FUNCTION
To deallocate a filerequester structure.
INPUTS
Freq - A pointer to the FileRequester structure you want
deallocated.
NAME
error = FileRequest( Freq );
-294 A0
FUNCTION
To put up the filerequester.
INPUTS
Freq - A pointer to an allocated and initialized FileRequester
structure.
RESULT
error - this will be an error code explained in "THE FILEREQUESTER"
chapter of this documentation.
NAME
num = FormatText( RPort, FString, Args );
D0 -300 A0 A1 A2
FUNCTION
To format a string and write it in a rastport.
INPUTS
Handle - A valid pointer to a RastPort.
FString - A pointer to a NULL terminated format string which can
hold the same format specifiers as the format string from
"Format". NOTE: The formatted output may NOT be larger
that 512 bytes (including the terminating 0 byte.).
Args - A pointer to an array in which the arguments are stored.
NOTE: C programmers must link with "tool.lib" to get the
arguments passed correctly to the routine.
RESULT
"num" will read the amount formatted characters written to the
rastport or NULL if an error occurred.
----------------------------------------------------------------------------
II. STRUCTURES AND DEFINITIONS
----------------------------------------------------------------------------
A pointer to the ToolBase structure is returned upon a successful call to
OpenLibrary().
struct ToolBase
{
struct Library LibNode; The actual library structure.
struct ExecBase *SysBase; A pointer to ExecBase.
struct DosLibrary *DOSBase; A pointer to DOSBase.
struct IntuitionBase *IntuitionBase; A pointer to IntuitionBase.
struct GfxBase *GfxBase; A pointer to GfxBase.
LONG SegList; A BPTR to the library code.
};
The library-base pointers in this structure can be used by a program to call
upon functions of any of those libraries.
A pointer to the TimeDelay structure is returned upon a successful call to
CreateTimeDelay().
struct TimeDelay
{
struct MsgPort *td_UserPort; A pointer to your message port.
struct MsgPort *td_ReplyPort; Used by the timer.device.
struct timerequest *td_TimeRequest; To specify the delay
};
The MemoryBlock, MemoryItem, BlockList and ItemList structures are used
internally to hold all allocations together in a MemoryChain structure.
struct MemoryChain
{
struct BlockList mc_Blocks; The list of blocks in the chain.
struct ItemList mc_Items; The list of items in the chain.
ULONG mc_BlockSize; The size of a block.
};
The Directory structure is used to hold the entries of a directory
together.
struct Directory
{
struct EntryInfo *dr_First; The first entry in the directory.
struct EntryInfo *dr_End; Always NULL.
struct EntryInfo *dr_Last; The last entry in the directory.
struct FileInfoBlock *dr_InfoBlock; Used to read the entries.
BPTR dr_Lock; Used to read the entries.
ULONG dr_NumEntries; The number of entries in the dir.
struct MemoryChain dr_DirMem; The memory used up.
};
The EntryInfo structure describes the entry.
struct EntryInfo
{
struct EntryInfo *ei_Next; The next entry.
struct EntryInfo *ei_Previous; The previous entry.
USHORT ei_Type; The type of entry (see below)
UBYTE ei_Name[32]; The entry name.
LONG ei_SizeBytes; The size in bytes (only with files)
LONG ei_SizeBlocks; The size in blocks (only with files)
LONG ei_ProtectionBits; The protection bits
struct DateStamp ei_Date; The entry date (not for devices)
};
The TOOL_VERSION and TOOL_REVISION defines represent the version and
revision number of the tool.library.
The LONGALLIGN macro is used by the library memory routines to make the
size of the allocation even to a 8 byte boundary.
MINDATE is a constant that represents the largest possible output of
GetDate().
ALL tells GetDate to convert the complete date.
ONLY_DAY tells GetDate only to convert the day of the week.
ONLY_DATE tells GetDate only to convert the date.
ONLY_TIME tells GetDate only to convert the time.
NO_CASE tells MatchPattern to check the character case also.
CASE tells MatchPattern not to check the character case.
ENTRY_FILE the entry is a file.
ENTRY_DIR the entry is a directory.
ENTRY_DEV the entry is a device. (only used by the FileRequester)
DIRBLOCK The size of a MemoryBlock in a directory.
----------------------------------------------------------------------------
III. THE FILEREQUESTER
----------------------------------------------------------------------------
Before you can call the FileRequester you must first call "AllocFreq" to
allocate and initialize a FileRequester structure and it's buffers. If the
allocation succeeded you will be returned a pointer to the following data
structure:
struct FileRequester
{
char *fr_HeadLine;
char *fr_FileName;
char *fr_DirName;
char *fr_DontShow;
USHORT fr_LeftEdge;
USHORT fr_TopEdge;
struct Window *fr_Caller;
struct Screen *fr_Screen;
struct Directory *fr_Directory;
USHORT fr_Flags;
USHORT fr_Colors[4];
BPTR fr_Handle;
LONG fr_Reserved;
};
The "fr_HeadLine" field points to a buffer in which you can copy the title
of the FileRequester window with a maximum of 28 bytes.
The "fr_FileName" field points to a buffer in which you can copy the default
filename. A maximum of 32 bytes is allowed here. After the FileRequester is
closed the last selected filename can be found in this buffer.
The "fr_DirName" field points to a buffer in which you can copy the default
pathname with or without a wildcard expansion. A maximum of 256 bytes is
allowed here. After the FileRequester is closed the last selected pathname
can be found in this buffer.
The "fr_DontShow" filed points to a buffer in which you can copy a wildcard
pattern which tells the FileRequester NOT to list the FILES which match this
pattern. A maximum of 32 bytes is allowed here.
With "fr_LeftEdge" and "fr_TopEdge" fields you can specify the co-ordinates
of the TopLeft corner of the FileRequester window on your screen. You should
calculate the position so that the FileRequester will fit on your screen.
Using incorrect values will result in a "FREQ_CANT_OPEN" when "FileRequest"
is called. You can use the "FREQ_WIDTH" and "FREQ_HEIGHT" constants which
specify the FileRequester window width and height to calculate a position on
your screen. The default settings are fr_LeftEdge = 10, fr_TopEdge = 15.
In the "fr_Caller" field you can put a pointer to a window which calls the
FileRequester. If this field is initialized the FileRequester will put a
very small requester in the TopLeft corner of this window to disable the
window from receiving IDCMP messages while the FileRequester is still up.
The requester is removed when the FileRequester is closed. By default this
field is set to NULL.
When you want the FileRequester to open on a custom screen you must put a
pointer to that screen in the "fr_Screen" field. This field defaults to NULL
which tells the FileRequester to use the WorkBench screen.
The "fr_Directory" field points to a Directory structure which is already
allocated and initialized by "AllocFreq" in which the FileRequester stores
the directories it reads. This may also hold the last directory read by the
FileRequester even after the FileRequester closed depending on whether the
"FR_NoPreserve" bit was set or not. (see below).
The "fr_Flags" field is used to switch certain functions in the FileRequester
on or off. See below for an explanation of the possible flags. This defaults
to "FR_ReturnVoid".
The "fr_Colors[4]" fields can be used to define your own colors depending on
whether the "FR_CustColor" flags is set or not. (see below).
The "fr_Handle" field is used to return a FileHandle to you is requested.
(see below).
Always set the "fr_Reserved" field to NULL because this field might be used
future version of the FileRequester/library.
THE POSSIBLE FLAGS
FR_NoPreserve
Normally when the FileRequester is closed the directory last
read will be kept in the "fr_Directory" field of the
FileRequester structure. This has the advantage that, when
the FileRequester is recalled, the directory does not have
to be read all over again. This also has the disadvantage
that the directory will take up atleast 5 KByte of your
memory. When the directory, on disk, changed the directory
in memory will not show this change, but if you press the
'HELP' key when the FileRequester is active the complete
directory is re-read into memory.
FR_NoDevs
Setting this flag disables the FileRequester from reading
and showing the mounted disk devices.
FR_NoSort
Setting this flag disables the FileRequester from sorting
the entries of a directory by sort and alphabetical.
FR_CustColor
If this flag is set the FileRequester will set the colors
defined in the "fr_Colors[4]" fields of the FileRequester
onto the screen it appears on saving the previous colors.
When the FileRequester is closed the old colors are reset.
FR_ReturnOld
Setting this flag tells the FileRequester to try to open
the selected file if the user closed the requester with OK.
The file will be opened using MODE_OLDFILE and the handle
is put in the "fr_Handle" field of the FileRequester
structure.
FR_ReturnNew
Setting this flag tells the FileRequester to try to open
the selected file if the user closed the requester with OK.
The file will be opened using MODE_NEWFILE and the handle
is put in the "fr_Handle" field of the FileRequester
structure.
FR_ReturnReadWrite
Setting this flag tells the FileRequester to try to open
the selected file if the user closed the requester with OK.
The file will be opened using MODE_READWRITE and the handle
is put in the "fr_Handle" field of the FileRequester
structure.
FR_NoInfo Setting this flag tells the FileRequester not to show the
".info" files.
FR_ReturnVoid
This specifies NOT to open the selected file. default.
POSSIBLE FILEREQUESTER RETURN CODES
FREQ_OK -> Everything OK. A file was selected and, if requested,
opened.
FREQ_CANT_OPEN -> The FileRequester could not be opened. This could mean
that not enough memory was available or that the
"fr_LeftEdge" and/or "fr_TopEdge" fields contains invalid
values.
FREQ_FILE_ERROR -> This means that the selected file failed to open.
FREQ_CANCELED -> This means that the user selected CANCEL or CLOSEWINDOW.
----------------------------------------------------------------------------
IV. HISTORY
----------------------------------------------------------------------------
VERSION 7-- -> TRASH !!!!
VERSION 7.1 -> Still not Released.
VERSION 7.2 -> The FileRequester now waits until the user selected
a gadget outside the file-selection area before it
starts to sort the entries.
VERSION 7.3 -> "MatchPattern" had a bug resulting in the matching
always being case sensitive. This is now fixed.
VERSION 7.4 -> I have put a pointer to the FileRequester window in
the "pr_WindowPtr" field of the Process structure
which results in the system requester appearing on
the same screen as the FileRequester. Also the
"DisplayBeep" function is called if a DOS error
occurred.
VERSION 7.5 -> When the "fr_NoPreserve" is not set and the
FileRequester is called the old directory is
displayed. When the directory had changed this
is not shown in the list. Now you can press the
"HELP" key and the directory is re-read.
VERSION 7.6 -> MAJOR BUG FOUND !! I did forget to call "Permit()"
after a call to "Forbid()" in the ReadDevs routine
of the FileRequester what resulted in some very
strange situations. This is now fixed (phew!).
VERY FIRST RELEASE !!!
VERSION 7.7 -> Fixed a few minor problems (NOT BUGS!) in the
FileRequester.
VERSION 7.8 -> Added "FR_NoInfo" flag for the FileRequester to
disable the showing of ".info" files.
VERSION 8.1 -> Added the "FormatText" routine. C Headers now includes
Lattice pragmas. "AllocItem()" now returns NULL if one
try's to allocate a chunk bigger than a memory block.
----------------------------------------------------------------------------
V. NOTES
----------------------------------------------------------------------------
Bug reports and suggestions (please !) too me at the following address:
Jan van den Baard
Bakkerstraat 176
3082 HE Rotterdam
Holland
